<!-- BeginDsi "dsi/head.html" -->
<!DOCTYPE html>
<html lang="en">
<head>
    <title>Embedthis GoAhead 3.2.1 Documentation</title>
    <meta name="keywords" content="embedded web server, web server software, embedded HTTP, application web server, 
        embedded server, small web server, HTTP server, library web server, library HTTP, HTTP library" />
    <meta name="description" content="Embedthis Sofware provides commercial and open source embedded web servers for 
        devices and applications." />
	<meta name="robots" content="index,follow" />
	<link href="../../../doc.css" rel="stylesheet" type="text/css" />
	<link href="../../../print.css" rel="stylesheet" type="text/css" media="print"/>
    <!--[if IE]>
    <link href="../../../iehacks.css" rel="stylesheet" type="text/css" />
    <![endif]-->
    <link href="http://www.google.com/cse/style/look/default.css" type="text/css" rel="stylesheet" />
    <script type="text/javascript">
        var _gaq = _gaq || [];
        _gaq.push(['_setAccount', 'UA-179169-5']);
        _gaq.push(['_trackPageview']);
        (function() {
            var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
            ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
            var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
        })();
    </script>
</head>

<body>
    <div class="top">
        <a class="logo" href="http://embedthis.com/products/goahead/">&nbsp;</a>
        <div class="topRight">
            <div class="search">
                <div id="cse-search-form"></div>
                <div class="version">Embedthis GoAhead 3.2.1</div>
            </div>
        </div>
        <div class="crumbs">
            <a href="../../../index.html">Home</a>
<!-- EndDsi -->
             &gt;<a href="index.html">Source Code</a>&gt; <b>Building from Source Code</b>
        </div>
    </div>
    <div class="content">
        <div class="contentRight">
            <h1>Quick Nav</h1>
            <ul>
                <li><a href="#platforms">Supported Platforms</a></li>
                <li><a href="#overview">Build Overview</a></li>
                <li><a href="#env">Prepare the Environment</a></li>
                <li><a href="#configuring">Configuring the Build</a></li>
                <li><a href="#main">Main Options</a></li>
                <li><a href="#cross">Cross Compilation</a></li>
                <li><a href="#building">Building</a></li>
                <li><a href="#customizing">Customizing</a></li>
                <li><a href="#installing">Installing</a></li>
                <li><a href="#repository">Source Repository</a></li>
                <li><a href="#keyFiles">Key File and Directories</a></li>
            </ul>
<!-- BeginDsi "dsi/sourceSeeAlso.html" -->
            <h1>See Also</h1>
            <ul class="nav">
                <li><a href="../../../guide/goahead/source/index.html">Working with Source</a></li>
                <li><a href="../../../guide/goahead/source/building.html">Building From Source</a></li>
                <li><a href="../../../guide/goahead/source/porting.html">Porting Guide</a></li>
                <li><a href="../../../ref/goahead/index.html">Programmers Reference</a></li>
                <li><a href="../../../guide/goahead/programmers/embedding.html">Embedding GoAhead</a></li>
                <li><a href="../../../guide/goahead/programmers/handlers.html">GoAhead Handlers</a></li>
                <li><a href="../../../guide/goahead/programmers/migrating.html">Migrating to GoAhead 3</a></li>
                <li><a href="../../../guide/goahead/users/index.html">Users Guide</a></li>
                <li><a href="../../../product/changeLog.html">Change Log</a></li>
            </ul>
<!-- EndDsi -->
        </div>
        <div class="contentLeft">
            <h1>Building from Source Code</h1>
            <p>This document describes the process to build the software from source for a supported platform.
            The source distribution contains all the necessary source files, headers and tools to
            reconfigure, build and verify the software. </p>
            
            <a id="platforms"></a>
            <p>Several build environments are supported:</p>
            <ul>
                <li><b>Linux</b> &mdash; Linux 2.6 with GNU C/C++</li>
                <li><b>Windows</b> &mdash; Microsoft Windows XP with Visual Studio 2010</li>
                <li><b>Mac OS X</b> &mdash; Mac OS X 10.7 (Lion) or later</li>
            </ul>
            <p>The source code has been designed to run on Free BSD, Linux, Mac OS X, Windows, VxWorks and other
            operating systems. It has been tested under Fedora Linux based on the Linux 2.6 Kernel, Microsoft Windows
            XP, Vista, 7 (32 and 64-bit), VxWorks 5.4, 6.3 and MAC OS X 10.7. Both single and multi-cpu systems are
            supported.</p>
            <p>If you are wanting to run the software to an unsupported platform, 
            you are welcome to try your hand at adapting it to a new platform. The software is very portable. See
            the <a href="porting.html">Porting Guide</a> for more details. </p>
            <p>If you want to build using source from the source code repository, please read these <a href=
                "#repository">additional instructions</a>.</p>
            <a id="overview"></a>
            <h2 class="section">Build Overview</h2>
            <p>GoAhead supports several methods of building from source:
            <ol>
                <li>Building via the <a href="http://ejscript.org/products/ejs/doc/guide/ejs/users/bit.html">Bit
                    (Build It) tool</a></li>
                <li>Building via make (or nmake on Windows)</li>
                <li>Building via an IDE such as Visual Studio or Xcode</li>
            </ol>
            <p>Building with Bit is the most flexible and offers the most control. It requires installing the
            <a href="http://ejscript.org/downloads/ejs/download.esp">Ejscript Product</a> which includes the
            <em>bit</em> tool. Using bit is required if you are cross-compiling or using static linking.</p>
            <p>Building with make or nmake is useful for a default (pre-configured)  build, but you do not 
            have the flexibility to configure
            the product for your system. Similarly, IDE builds are convenient, but are somewhat fixed in the software
            configuration they build. We recommend building with Bit. It is fast, flexible and configurable.</p>
            <a id="env"></a>
            <h3>Preparing the Environment</h3>
            <p>Before building, you may need to install required tools such as cross-compilers, SDKs, and system
            libraries. If you wish to build GoAhead with the support of third-party packages such as 
            MatrixSSL or OpenSSL, you may need to download the source from the relevant vendor and build the
            required libraries for GoAhead to utilize.</p>
            <h4>Windows</h4>
            <p>To build on Windows, you will need to install Microsoft Visual Studio 10.0 or later. Either the full 
            product or the express editions will work fine. You will also need to 
            install the <a href="http://msdn.microsoft.com/en-us/windowsserver/bb980924.aspx">Windows SDK</a>.
            <p>Before building or configuring, you need to define certain Microsoft compiler environment variables as
            described in the Microsoft Visual Studio installation. These variables are the PATH, INCLUDE and LIB
            variables. They need to be
            defined so they will contain references to where the Microsoft compiler and libraries are installed on your
            system. The <em>vcvarsall.bat</em> command supplied with Visual Studio is the normal way to define these
            variables.</p>
            <h4>Unix / Linux</h4>
            <p>To build on Linux, you may need to install the libpam and zlib libraries.</p>
            <a id="make"></a>
            <h3>Building with Make/Nmake</h3>
            <p>GoAhead provides a suite of Makefiles under the projects directory for common platforms. These are 
            single, simple Makefiles that build a generic configuration of GoAhead. You may need to edit the Makefile
            for your platform to adjust compiler or linker options. A top level Makefile is provided that attempts to
            determine the correct project Makefile for your system. To build using make, type the following in the top
            directory of the source code:</p>
            <pre>make</pre>
            <p>Alternatively, invoke the platform Makefile specifically. For example:</p>
            <pre>make -f projects/goahead-macosx.mk</pre>
            <p>To build on Windows with nmake, type:
            <pre>nmake -f projects\goahead-windows.nmake</pre>
            <a id="sh"></a>
            <h3>Building with Shell Scripts</h3>
            <p>GoAhead provides simple shell scripts to build GoAhead. Unlike building with make, bit or and IDE, these
            scripts will always completely rebuild the product from source. For example:</p>
            <pre>bash projects/linux-x86.sh</pre>
            
            <a id="ide"></a>
            <h3>Building with an IDE</h3>
            <p>GoAhead provides Visual Studio and Xcode projects. To build GoAhead with the Visual Studio project, 
            run Visual Studio 2010 or later (The Express editions are fine to use). Then open the
            projects/goahead-windows.sln Solution project. Select Build Solution to build. Select GoAhead as the start up
            project to debug.</p>
            <p>To build GoAhead with the Xcode on Mac OS X, run Xcode and open the
            <em>projects/goahead-macosx.xcodeproj</em> project.  Then select Product-&gt;Build to build. To debug, you will
            need to create use Product-&gt;Edit Scheme to set the executable to run under the Info tab, and define the
            working directory under the Options tab. Set the working directory to the "test" directory of the source
            tree. </p> <p>If you have built first with bit, make, nmake or shell scripts, you should remove the
            generated platform output directory and all its contents before building with the IDE.</p>
            <pre>bash projects/linux-x86.sh</pre>
            
            <a id="bit"></a>
            <h3>Building with Bit</h3>
            <p>The procedure for building with Bit is the same for all supported platforms. The 
            <a href="http://ejscript.org/products/ejs/doc/guide/ejs/users/bit.html">bit</a> tool is used to configure
            and to build GoAhead. Bit is part of the <a href="http://ejscript.org">Ejscript</a> JavaScript environment. Click
            to <a href="http://ejscript.org/downloads/ejs/download.esp">Download Ejscript</a>.</p>
            
            <a id="configuring"></a>
            <h2 class="section">Configure GoAhead</h2>
            <p>GoAhead may be customized for environment by running <em>bit configure</em>. This is used to select
            features, options, and integrate third-party packages. </p>
            <p>A <em>configure</em> script is provided to give a familiar "configure" command interface to the
            <em>bit</em> tool. This script simply invokes the <em>bit configure</em> command and passed all command line
            options to bit.</p>
           
            <p>During configuration, <em>bit</em> will read the master <i>main.bit</i> configuration file. This
            file controls and specifies  essential GoAhead settings. You can edit this file to suit your neds. After
            configuration, several output files are created that contain settings for each specified platform.</p>
            <ul>
                <li>A bit file that specifies the platforms to build named: start.bit</li>
                <li>A bit file for each platform named: OS-ARCH[-CPU].bit</li>
                <li>A source header with for the build configuration named: OS-ARCH[-CPU]-PROFILE/inc/bit.h</li>
                <li>An output products directory for each platform named: OS-ARCH[-CPU]-PROFILE</li>
            </ul>
            <p>where OS is the name of the operating system, ARCH is the name of the CPU architecture and PROFILE
            is the build profile name, typically "debug" or "release". For example: linux-x86-debug.</p>
            <p>The generated Bit files are readable JavaScript files that contain the settings to control the build
            when Bit is run. When compiling, all source code includes the relevant platform <em>bit.h</em> header to
            configure how the source is built.</p>
            <h3>Running Configure</h3>
            <p>You may run the configure script with no options to accept the factory defaults &mdash; this is a good
            starting point:</p> 
            <pre>./configure</pre>
            <p>Alternatively, invoke bit directly:</p>
            <pre>bit configure</pre>
            <p>You may also supply options to configure which are passed onto <em>bit</em>, for example:</p>
            <pre>
./configure --release --without all
</pre>
            <p>The <em>--release</em> switch instructs bit to build an optimized production release. This will disable
            non-essential debugging code and logging. The <em>--without all</em> switch will disable non-essential
            features to create a minimal build.</p>
            <a id="options"></a>
            <h2 class="section">Configure Options</h2>
            <p>The tables below describe the configuration options.
            <h3>Basic Configure Options</h3>
            <table title="options">
                <thead>
                    <tr>
                        <th>Option</th>
                        <th>Description</th>
                    </tr>
                </thead>
                <tbody>
                <tr>
                    <td>--debug</td>
                    <td>Build a debug build. This builds a development, non-optimized build with debug symbols.</td>
                </tr>
                <tr>
                    <td>--help</td>
                    <td>Display the bit program usage help.</td>
                </tr>
                <tr>
                    <td class="nowrap">--set KEY=VALUE</td>
                    <td>Set the value of a property in the bit settings collection. For example: "--set
                        product=myProduct".</td>
                </tr>
                <tr>
                    <td>--quiet, -q</td>
                    <td>Run quietly without progress trace.</td>
                </tr>
                <tr>
                    <td>--release</td>
                    <td>Build a release build. This builds an optimized, production-ready build of the software.</td>
                </tr>
                <tr>
                    <td>--static</td>
                    <td>Configure for static linking.</td>
                </tr>
                <tr>
                    <td>--verbose, -v</td>
                    <td>Run verbosely and emit more detailed progress trace.</td>
                </tr>
                </tbody>
            </table>
            <h3>Cross Building</h3>
            <table title="types">
                <thead>
                    <tr>
                        <th>Option</th>
                        <th>Description</th>
                    </tr>
                </thead>
                <tbody>
                <tr>
                    <td class="nowrap">--platform OS-ARCH[-CPU]</td>
                    <td><p>Specify the target platform for which to build. For example "-platform linux-arm". 
                        Supported operating systems are: freebsd, linux, macosx, vxworks and windows. 
                        Supported architectures are: arm, mips, ppc, x64 or x86.
                        If the -platform option is omitted, the local system is added as the target platform.  You may
                        use the 'local' alias to indicate the local platform.  Multiple platforms may be specified. </p>
                        <p>The optional CPU component specifies a CPU instance to tune for. The CPU setting is used
                        in a -DCPU=VALUE compiler define. For example: "-platform linux-arm-arm7tdmi".</p>
                    </td>
                </tr>
            </tbody>
            </table>
            <h3>Optional Packages</h3>
            <table title="packages">
                <thead>
                    <tr>
                        <th>Option</th>
                        <th>Description</th>
                    </tr>
                </thead>
                <tbody>
                <tr>
                    <td class="nowrap">--with PACKAGE[=dir]</td>
                    <td>Specify if a PACKAGE should be included in the build. The optional directory is the path to
                        the source distribution of the package. If the directory is omitted, bit will search the
                        local system for the package in well known places.</td>
                </tr>
                <tr>
                    <td>--without PACKAGE</td>
                    <td>Do not include the PACKAGE in the build.
                        Use --without all to disable all possible non-essential packages.</td>
                </tr>
                </tbody>
            </table>
            <h3>Example Use</h3>
            <pre>configure --with openssl=/usr/src/openssl</pre>
            <h3>Packages</h3>
            <p>The following table describes the packages that can extend GoAhead configure. 
            The use of the Internal/External field states whether the package is shipped internally with the GoAhead source
            code, or whether it is an external third party package.</p>
            <table title="env">
                <thead>
                    <tr>
                        <th>Package</th>
                        <th>Integrated</th>
                        <th>Description</th>
                    </tr>
                </thead>
                <tbody>
                <tr>
                    <td>est</td>
                    <td>Internal</td>
                    <td>Embedded Security Transport. SSL stack.</td>
                </tr>
                <tr>
                    <td>matrixssl</td>
                    <td>External</td>
                    <td>MatrixSSL SSL stack. Requires a commerical license from PeerSec.</td>
                </tr>
                <tr>
                    <td>mocana</td>
                    <td>External</td>
                    <td>Mocana NanoSSL stack. Requires a commerical license from Mocana.</td>
                </tr>
                <tr>
                    <td>openssl</td>
                    <td>External</td>
                    <td>OpenSSL SSL stack. Requires OpenSSL libraries.</td>
                </tr>
                </tbody>
            </table>
            <p>The following table describes the tool packages that can be used when building, running and 
            managing GoAhead. 
            The use of the Internal/External field documents whether the package is shipped internally with the GoAhead source
            code, or whether it is an external third party package.</p>
            <table title="env">
                <thead>
                    <tr>
                        <th>Package</th>
                        <th>Integrated</th>
                        <th>Description</th>
                    </tr>
                </thead>
                <tbody>
                <tr>
                    <td>doxygen</td>
                    <td>External</td>
                    <td>C API documentation generator.</td>
                </tr>
                <tr>
                    <td>dsi</td>
                    <td>External</td>
                    <td>Dev Side Includes. Simple static web page templates.</td>
                </tr>
                <tr>
                    <td>http</td>
                    <td>Internal</td>
                    <td>Http test client program.</td>
                </tr>
                <tr>
                    <td>man</td>
                    <td>External</td>
                    <td>Manual page reader and renderer.</td>
                </tr>
                <tr>
                    <td>man2html</td>
                    <td>External</td>
                    <td>Program to convert man pages to HTML.</td>
                </tr>
                <tr>
                    <td>pmaker</td>
                    <td>External</td>
                    <td>Native package maker. This resolves to InnoSetup on Windows and PackageMaker on MAC OS X.</td>
                </tr>
                <tr>
                    <td>utest</td>
                    <td>External</td>
                    <td>Ejscript unit test framework. See http://ejscript.org.</td>
                </tr>
                <tr>
                    <td>zip</td>
                    <td>External</td>
                    <td>Zip compression program. Used when creating installable packages.</td>
                </tr>
                </tbody>
            </table>
            <a name="main"></a>
            <h3>Main Configuration Options</h3>
            <p>The main.bit configuration file specifies build-time defaults. Some of the important values
            are listed below:</p>
            <table title="main">
                <tbody>
                    <tr>
                        <td class="pivot">accessLog</td>
                        <td>Enable request URI logging to an access log</td>
                    </tr>
                    <tr>
                        <td class="pivot">certificate</td>
                        <td>SSL certificate file</td>
                    </tr>
                    <tr>
                        <td class="pivot">cgi</td>
                        <td>Set to true to enable the CGI handler</td>
                    </tr>
                    <tr>
                        <td class="pivot">javascript</td>
                        <td>Enable the Javascript template handler</td>
                    </tr>
                    <tr>
                        <td class="pivot">key</td>
                        <td>SSL private key</td>
                    </tr>
                    <tr>
                        <td class="pivot">legacy</td>
                        <td>Enable GoAhead 2.X APIs to improve backward compatibility</td>
                    </tr>
                    <tr>
                        <td class="pivot">listens</td>
                        <td>List of endpoints on which GoAhead will listen</td>
                    </tr>
                    <tr>
                        <td class="pivot">limitBuffer</td>
                        <td>General I/O buffer size</td>
                    </tr>
                    <tr>
                        <td class="pivot">limitFilename</td>
                        <td>Maximum filename size</td>
                    </tr>
                    <tr>
                        <td class="pivot">limitFiles</td>
                        <td>Maximum number of files/sockets (ulimit)</td>
                    </tr>
                    <tr>
                        <td class="pivot">limitHeader</td>
                        <td>Maximum size of the request header</td>
                    </tr>
                    <tr>
                        <td class="pivot">limitNumHeaders</td>
                        <td>Maximum number of header lines in the request</td>
                    </tr>
                    <tr>
                        <td class="pivot">limitParseTimeout</td>
                        <td>Maximum time to parse the request headers</td>
                    </tr>
                    <tr>
                        <td class="pivot">limitPassword</td>
                        <td>Maximum size of a password</td>
                    </tr>
                    <tr>
                        <td class="pivot">limitPost</td>
                        <td>Maximum size of the incoming request body</td>
                    </tr>
                    <tr>
                        <td class="pivot">limitPut</td>
                        <td>Maximum size of a put request</td>
                    </tr>
                    <tr>
                        <td class="pivot">limitSessionLife</td>
                        <td>Default session lifespan in seconds</td>
                    </tr>
                    <tr>
                        <td class="pivot">limitSessionCount</td>
                        <td>Maximum number of sessions</td>
                    </tr>
                    <tr>
                        <td class="pivot">limitString</td>
                        <td>Default string size</td>
                    </tr>
                    <tr>
                        <td class="pivot">limitTimeout</td>
                        <td>Request inactivity timeout in seconds</td>
                    </tr>
                    <tr>
                        <td class="pivot">limitUri</td>
                        <td>Maximum URI size</td>
                    </tr>
                    <tr>
                        <td class="pivot">limitUpload</td>
                        <td>Maximum size of a file upload request</td>
                    </tr>
                    <tr>
                        <td class="pivot">pam</td>
                        <td>Build with Unix PAM authentication password support</td>
                    </tr>
                    <tr>
                        <td class="pivot">trace</td>
                        <td>Trace log destination. Uses the form: path:level</td>
                    </tr>
                    <tr>
                        <td class="pivot">stealth</td>
                        <td>Enable stealth mode. Disable OPTIONS and TRACE methods.
                           Enabled by default.</td>
                    </tr>
                    <tr>
                        <td class="pivot">upload</td>
                        <td>Enable the upload handler</td>
                    </tr>
                    <tr>
                        <td class="pivot">uploadDir</td>
                        <td>Directory to store uploaded files</td>
                    </tr>
                </tbody>
            </table>
            <h3>Environment Variables</h3>
            <p>When cross-building, certain environment variables may be passed to the configure script and on to 
            <em>bit</em> to configure the compiler and linker paths and flags. </p>
            <table title="env">
                <thead>
                    <tr>
                        <th>Variable</th>
                        <th>Description</th>
                    </tr>
                </thead>
                <tbody>
                <tr>
                    <td>AR</td>
                    <td>Path to the archiver program to use to archive libraries for the target system.</td>
                </tr>
                <tr>
                    <td>CC</td>
                    <td>Path to the C/C++ compiler to use to compile for the target system.</td>
                </tr>
                <tr>
                    <td>CFLAGS</td>
                    <td>Compiler control flags</td>
                </tr>
                <tr>
                    <td>DFLAGS</td>
                    <td>Compiler preprocessor defines</td>
                </tr>
                <tr>
                    <td>IFLAGS</td>
                    <td>Include directory options</td>
                </tr>
                <tr>
                    <td>LD</td>
                    <td>Path to the linker program to link objects for the target system.</td>
                </tr>
                <tr>
                    <td>LDFLAGS</td>
                    <td>Linker flags. E.g. -Ldir to specify a non-standard directory for libraries.</td>
                </tr>
                </tbody>
            </table>
            <h3>Example Use</h3>
            <pre>
CC=/opt/bin/ccarm configure
</pre>
            <h3>Configure Examples</h3>
            <p>Here are some useful configure command options.</p>
            <p>To configure for building outside a source tree. This supports building from source from a 
                read-only file system.</p>
            <pre>configure --config /path/to/source</pre>
            <p>To configure for a debug build with debug symbols:</p>
            <p>To configure without TLS/SSL:</p>
            <pre>configure --without ssl</pre>
            <p>To configure to build for 32-bit X86 (when on a 64-bit system):</p>
            <pre>configure --platform linux-x86</pre>
            <p>Use the "--help" switch to see the available options or see the <a
                href="http://ejscript.org/products/ejs/doc/guide/ejs/users/bit.html">Bit</a> document for more details.</p> 
            
            <a id="packages"></a>
            <h2 class="section">Building with Third-Party Packages</h2>
            <p>The configuration process supports the resolution of external packages that extend and enhance GoAhead, 
                such as MatrixSSL and OpenSSL. By default, GoAhead can locate these packages if the source
                distributions are installed in standard locations. Otherwise, the packages can be identified by using
                <em>configure --with PACKAGE=PATH</em> switch. This specifies the path to the package source directory.</p>
            <p>For example, to build with Ejscript, follow these steps:</p>
            <ol>
                <li>Download Ejscript from
                <a href="https://github.com/embedthis/ejs-2">https://github.com/embedthis/ejs-2</a>. Contact
                <a href="mailto:sales@embedthis.com">sales@embedthis.com</a> if you require a commercial license.</li>
                <li>Configure and build Ejscript via the Ejscript configure command in the Ejscript directory:
                    <pre>./configure
make                        # Does a bootstrap build
*/bin/bit configure build   # Configure and build
sudo bit install            # Install so GoAhead can use bit
</pre></li> 
                <li>Then, from the GoAhead source directory run the GoAhead configure:
                <pre>./configure --with openssl
bit           # To build GoAhead with OpenSSL support</pre></li>
            </ol>
            <a id="cross"></a>
            <h2 class="section">Cross Compilation</h2>
            <p>To build a product for platform different to that of the local system is called <em>cross compiling</em>.
            Sometimes this cross compiling is just for a different instruction set (say x64 instead of x86). Other
            times, it is for a completely different operating system and/or CPU architecture. In such cases a
            cross-compiler may be required to build for the target platform.</p>
            <p>Bit supports cross compiling via the <em>-platform PLATFORM</em> bit configure option. This option adds a
            platform to the list of platforms to be made. Multiple platforms may be
            specified and the 'local' platform alias may be used for the local development platform.</p>
            <pre>bit -platform linux-arm-arm7 -configure . </pre>
            <p>This will create a windows-x64.bit configuration file and a start.es that references it. The
            platform switch does not need to be restated after configuration.</p>
            <p>Some products require local building to make tools that are required to build for any platform. These
            products add a "platforms: ['local']" property to their settings collection in the main.bit file. This
            automatically adds the local platform to the platforms list and is the same as adding '-platform local' on
            the command line when configuring.</p>
            <h3>Platforms</h3>
            <p>A platform specification is of the form OS-ARCH, where the
            supported operating systems are: freebsd, linux, macosx, vxworks and windows. The ARCH field is
            one of arm, mips, ppc, x64 or x86. X64 is the AMD/Intel 64-bit instruction set and x86 is the Intel X86
            Pentium instruction set. You may also use i386 or i686 for specific Intel X86 instruction sets.
            The CPU field is optional and specifies a CPU to tune for.</p>
            <h3>Environment Variables</h3>
            <p>When cross compiling, you may need to inform <b>configure</b> about your cross-compilation tool chain.
            Bit will do its best to discover the installed cross tool chain and will look in well known
            directories to locate the compiler, linker and other required tools. If <em>bit</em> cannot locate the 
            tool chain, you can supply the tool chain details via the environment variables: CC, CFLAGS, DFLAGS, IFLAGS
            LD and LDFLAGS. These will be used to define and configure the cross-compilation tool chain. 
            <p>For example, here is a cross-compilation <b>configure</b> command line:</p>
            <pre>
CC=/opt/bin/cc.exe \
LD=/opt/bin/cc.exe \
CFLAGS=-I/opt/include \
./configure --debug --platform linux-arm-arm7
</pre>
            
            <a id="building"></a>
            <h2 class="section">Building Bit</h2>
            <p>Once the build configuration is complete, you may proceed to build the source code by typing:</p>
            <pre>
bit
</pre>
            <p>This will build the software. If cross compiling, depending on your configuration, it may build twice:
            once for the local system and once for the target platform. 
            <h3>Useful Bit options and targets</h3>
            <p>Here are some useful bit examples:</p>
            <pre>bit --show     # Show actual commands while building
bit --why      # Show why each target is or is not being built 
bit --dump     # Dump the combined bit configuration in one file
bit rebuild    # Rebuild all targets
bit clean      # Clean all built targets
bit rebuild    # Rebuild all targets
bit install    # Install the built software locally
bit --help     # Show bit usage</pre>
            
            <h3>Static Linking</h3>
            <p>On some platforms, it is desirable to statically link GoAhead. The default bit files
            are setup to build GoAhead using shared libraries and to build the loadable modules separately. If you want to
            statically link GoAhead and the modules together, run configure with the <i>--static</i> option and then 
            rebuild.</p>
<pre>
./configure --static
bit
</pre>
            <h3>Serving from ROM</h3>
            <p>GoAhead supports systems without a file system where web documents are compiled into C code and served from
            ROM. To enable this, configure with the <em>--rom</em> switch.
            <pre>
configure --rom
</pre>
            <p>See <a href="../programmers/rom.html">Serving Pages from ROM</a> for more information.</p>
<!--
            <a id="installing"></a>
            <h2 class="section">Installing</h2>
            <p>You can install the newly built software via:</p>
            <pre>
sudo bit install
</pre>
            <p>You can remove by:</p>
            <pre>
sudo bit uninstall
</pre>
            <h3>Create an Installable Release</h3>
            <p>After building, bit can create installable packages of the software:</p>
            <pre>bit package</pre>
            <p>The release packages are placed under the <em>releases</em> directory. The <em>goahead-tar.tgz</em> image is a
            simple compressed tar archive of the binary release. If you are embedding goahead into another application,
            you can extract the required GoAhead files from this release archive and include them with your application.
            Alternatively, you can extract them from the staging directory
            under the <em>OS-ARCH[-CPU]-PROFILE/pkg/bin/goahead-VERSION/contents</em> directory. </p>
-->
            <a id="repository"></a>
            <h2 class="section">Building from the Source Code Repository</h2>
            <p>You can checkout a copy of the product source code via:</p>
            <pre>
 git clone <a href="https://github.com/embedthis/goahead">https://github.com/embedthis/goahead</a>
</pre>
            <p>There are three repository branches that you can select:
            <ul>
                <li>stable &mdash; Source code for the most recent release.</li>
                <li>master &mdash; Most recent, quasi-stable development snapshot.</li>
                <li>dev &mdash; Current source code under active development. Least stable.</li>
            </ul>
            <p>Once checked out, the normal instructions for building from source apply.</p><a id="keyFiles"></a>
            <h2 class="section">Key Files and Directories</h2>
            <p>Source trees contain the following key directories under the top directory.</p>
            <table title="dirs">
                <thead>
                    <tr>
                        <th>Directory</th>
                        <th>Subdirectory</th>
                        <th>Description</th>
                    </tr>
                </thead>
                <tbody>
                <tr>
                    <td>bits</td>
                    <td></td>
                    <td>Bit configuration and scripts.</td>
                </tr>
                <tr>
                    <td></td>
                    <td>packs</td>
                    <td>Bit extension packs.</td>
                </tr>
                <tr>
                    <td></td>
                    <td class="nowrap">OS-ARCH[-CPU]-PROFILE</td>
                    <td>Build output directory.</td>
                </tr>
                <tr>
                    <td></td>
                    <td>inc</td>
                    <td>Include headers</td>
                </tr>
                <tr>
                    <td></td>
                    <td>obj</td>
                    <td>Directory to hold generated objects.</td>
                </tr>
                <tr>
                    <td>releases</td>
                    <td></td>
                    <td>Generated release distributions.</td>
                </tr>
                <tr>
                    <td>package</td>
                    <td></td>
                    <td>Scripts for creating release distribution packages.</td>
                </tr>
                <tr>
                    <td>projects</td>
                    <td></td>
                    <td>Microsoft Visual Studio and Eclipse project and workspace files.</td>
                </tr>
                <tr>
                    <td>src</td>
                    <td></td>
                    <td>Product source code.</td>
                </tr>
                <tr>
                    <td></td>
                    <td>deps</td>
                    <td>Dependant libraries including MPR, Http, Pcre.</td>
                </tr>
                <tr>
                    <td></td>
                    <td>samples</td>
                    <td>Sample source code and examples</td>
                </tr>
                <tr>
                    <td>test</td>
                    <td></td>
                    <td>Unit and integration tests.</td>
                </tr>
            </tbody>
            </table>
            <h3>Key Build Files</h3>
            <table title="files">
                <thead>
                    <tr>
                        <th>Name</th>
                        <th>Description</th>
                    </tr>
                </thead>
                <tbody>
                <tr>
                    <td>configure</td>
                    <td>Build configuration script. This invokes Bit to configure GoAhead on the development system.</td>
                </tr>
                <tr>
                    <td class="nowrap">OS-ARCH[-CPU].bit</td>
                    <td>Platform specific Bit file. There will be one platform bit file for each target platform.</td>
                </tr>
                <tr>
                    <td>main.bit</td>
                    <td>Main Bit file for GoAhead. It specifies the GoAhead key settings and configured options.</td>
                </tr>
                <tr>
                    <td>start.bit</td>
                    <td>Startup bit file for GoAhead. This file refers to the relevant Bit files for platforms.</td>
                </tr>
                <tr>
                    <td>*/inc/bit.h</td>
                    <td>Build header created by Bit and included in all source files.</td>
                </tr>
                </tbody>
            </table>
        </div>
    </div>
<!-- BeginDsi "dsi/bottom.html" -->
	<div class="bottom">
		<p class="footnote"> 
            <a href="../../../product/copyright.html" >&copy; Embedthis Software LLC, 2003-2014.
            All rights reserved. Embedthis and Embedthis GoAhead are trademarks of Embedthis Software LLC.</a>
		</p>
	</div>
    <script src="http://www.google.com/jsapi" type="text/javascript"></script>
    <script type="text/javascript"> 
      google.load('search', '1', {language : 'en'});
      google.setOnLoadCallback(function() {
        var customSearchControl = new google.search.CustomSearchControl(
          '000262706376373952077:1hs0lhenihk');
        customSearchControl.setResultSetSize(google.search.Search.FILTERED_CSE_RESULTSET);
        var options = new google.search.DrawOptions();
        options.enableSearchboxOnly("http://embedthis.com/search.html");
        customSearchControl.draw('cse-search-form', options);
      }, true);
    </script>
    <script type="text/javascript">
        var _gaq = _gaq || [];
        _gaq.push(['_setAccount', 'UA-179169-5']);
        _gaq.push(['_trackPageview']);
        (function() {
            var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
            ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
            var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
        })();
    </script>
</body>
</html>
